home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 007 / tshell10.arc / TSHELL.DOC < prev   
Text File  |  1987-03-14  |  8KB  |  243 lines
  1.  
  2.  
  3.  
  4.                                    TSHELL
  5.  
  6.  
  7.                       Turbo Pascal Preprocessor Shell
  8.  
  9.  
  10.                           Version 1.0 (14-Mar-87)
  11.  
  12.  
  13.  
  14.   
  15.         Copyright (C) 1987 by Samuel H. Smith;  All Rights Reserved.
  16.  
  17.  
  18.  
  19.       You may copy and distribute this program freely, provided that:
  20.          1)   No fee is charged for such copying and distribution, and
  21.          2)   It is distributed ONLY in its original, unmodified state.
  22.  
  23.  
  24.           if you like this program, and find it of use, then your 
  25.           contribution of $10 will be appreciated.  
  26.  
  27.  
  28.  
  29.                        Please refer all inquiries to:
  30.                             S. H. Smith
  31.                             5119 N. 11th Ave 332
  32.                             Phoenix, AZ 85013
  33.  
  34.  
  35.  
  36.  
  37.     This program allows you to use a number of C-like preprocessor 
  38.     statements in a Turbo Pascal source file.  It interprets the 
  39.     statements and passes the processed text on to the Turbo compiler 
  40.     for further processing. 
  41.  
  42.     The TSHELL program will load TURBO.COM into memory, install the 
  43.     preprocessor shell, and enter the Turbo main menu.   At this point, 
  44.     Turbo Pascal can be used as always, except that the new 
  45.     preprocessor commands can be used in any source file. 
  46.  
  47.     To start a Turbo Pascal session with the preprocessor shell, enter: 
  48.        TSHELL
  49.     on the DOS command line.
  50.  
  51.     
  52.     A stand-alone (batch) version of the preprocessor is also 
  53.     available.  A single turbo source file can be preprocessed and 
  54.     written to another file with this command: 
  55.        TPP file.in >file.out
  56.     This command reads file.in, preprocesses it and writes the result 
  57.     to file.out.   This command is useful when you want to convert a 
  58.     file that uses the TSHELL preprocessor back into a normal Turbo 
  59.     Pascal source. 
  60.  
  61.  
  62.     Overview
  63.     --------
  64.  
  65.  
  66.     The following C preprocessor directives are understood:
  67.  
  68.        #define NAME STRING    ;replace all instances of NAME with STRING
  69.     
  70.        #undef NAME            ;delete definition of NAME
  71.     
  72.        #ifdef NAME            ;compile only if NAME is defined
  73.     
  74.        #ifndef NAME           ;compile if NAME is not defined
  75.     
  76.        #else                  ;compile otherwise
  77.     
  78.        #endif                 ;resume normal compilation
  79.     
  80.        #pragma NOEXPAND       ;do not expand #defines in following lines
  81.     
  82.        #pragma EXPAND         ;resume #define expansion
  83.     
  84.        #pragma LIST           ;list preprocessed lines to screen
  85.     
  86.        #pragma NOLIST         ;stop listing
  87.     
  88.        #include <file>        ;include another file
  89.  
  90.  
  91.  
  92.     The following special keywords are predefined:
  93.  
  94.        SYSTEM_DATE            ;the time/date when compile was started
  95.     
  96.        LAST_UPDATE            ;last modification time of current file
  97.     
  98.        CURRENT_FILE           ;name of current file
  99.  
  100.  
  101.  
  102.     Note that keyword replacement takes place only when the keyword in 
  103.     the source is surrounded by delimiters.   A replacement will not 
  104.     take place if the keyword is preceeded or followed by a number or a 
  105.     letter.   This preprocessor WILL make replacements within literals 
  106.     and comments - beware! 
  107.  
  108.  
  109.  
  110.     Preprocessor commands
  111.     ---------------------
  112.  
  113.     Preprocessor commands must be alone on a line.  Indentation is 
  114.     allowed, but there cannot be a space between the '#' and the 
  115.     command keyword.   
  116.  
  117.  
  118.     #define NAME REPLACEMENT
  119.        This command arranges for any future instances of NAME to be 
  120.        replaced by REPLACEMENT.   
  121.     
  122.        This command has two main uses: 
  123.           1. to provide a simple macro replacement facility, and 
  124.           2. to control conditional compilation (in conjunction with 
  125.              the #ifdef and #ifndef commands). 
  126.  
  127.  
  128.     #undef NAME
  129.        Remove any definition of NAME.
  130.  
  131.  
  132.     #ifdef NAME
  133.        If NAME has been defined with #define, the following code will 
  134.        compile as normal.  Otherwise, the following code will be 
  135.        excluded from the compilation.   Normal compilation resumes with 
  136.        an #endif statement.   For example:
  137.  
  138.            #ifdef FAST_VIDEO
  139.               fast_display(x,y,'display data');
  140.            #else
  141.               gotoxy(x,y);
  142.               writeln(con,'display data');
  143.            #endif
  144.            
  145.  
  146.     #ifndef NAME
  147.        Like #ifdef but compiles code if the NAME has NOT been defined.
  148.  
  149.     #else
  150.        Used with #ifdef to provide alternative code for cases where
  151.        the keyword is not defined. 
  152.  
  153.     #endif
  154.        Terminates a #ifdef block of code and resumes normal 
  155.        compilation. 
  156.  
  157.  
  158.  
  159.     #pragma NOEXPAND
  160.        This command stops macro expansion.  It is used in cases where 
  161.        macro expansion is not desired.   This also speeds up 
  162.        compilation by eliminating the need to scan each line for 
  163.        keywords. 
  164.  
  165.     #pragma EXPAND
  166.        This command resumes normal expansion of macros.
  167.  
  168.  
  169.  
  170.     #pragma LIST
  171.        This command causes the source code to be listed to the screen 
  172.        after macro expansion had taken place. 
  173.  
  174.     #pragma NOLIST
  175.        This command disables the source listing.
  176.  
  177.  
  178.  
  179.     #include <file>
  180.        This command is passed on to turbo pascal as 
  181.           {$I file}
  182.        where it is processed as usual.   A future version of TSHELL 
  183.        might implement nested include files through this command.
  184.  
  185.  
  186.  
  187.  
  188.     Predefined keywords
  189.     -------------------
  190.  
  191.     SYSTEM_DATE
  192.        This keyword will be replaced with the time and date when the 
  193.        compile was started.  It has the form:  dd-mmm-yy hh:mm:ss. 
  194.  
  195.     LAST_UPDATE
  196.        This keyword will be replaced with the last update date of the 
  197.        current source file. 
  198.  
  199.     CURRENT_FILE
  200.        This keyword will be replaced with the full pathname of the 
  201.        current source file. 
  202.  
  203.  
  204.  
  205.  
  206.     Program requirements and limitations
  207.     ------------------------------------
  208.  
  209.     Version 1.0 of TSHELL works only with Turbo Pascal version 3.01a.  
  210.     Future releases will work with more versions of Turbo.   Note that 
  211.     since TPP does not use TURBO.COM, it works with any version of 
  212.     Turbo Pascal.
  213.  
  214.  
  215.     Memory used:                   About 50k of RAM, in addition to 
  216.                                    that normally used by TURBO.COM. 
  217.  
  218.     Number of #define's:           100 different keywords can be 
  219.                                    defined.
  220.  
  221.     Maximum keyword length:        Keywords can be up to 30 characters 
  222.                                    in length.  Keywords must follow 
  223.                                    the same conventions as Turbo 
  224.                                    Pascal identifiers.
  225.  
  226.     Maximum replacement length:    Replacement strings can be up to 70 
  227.                                    characters long.   Note that the 
  228.                                    line length after macro expansion 
  229.                                    cannot exceed 128 characters.  This 
  230.                                    limit is imposed by Turbo Pascal.
  231.  
  232.     #ifdef nesting:                #ifdef and #ifndef statements can 
  233.                                    be nested up to 10 levels.
  234.  
  235.     #include nesting:              #include statements are still 
  236.                                    handled by Turbo Pascal and cannot 
  237.                                    be nested.  A future version of 
  238.                                    TSHELL will allow include file 
  239.                                    nesting.
  240.  
  241.  
  242.  
  243.